5 * Created on Aug 29, 2014
7 * Copyright © 2014 Wikimedia Foundation and contributors
9 * This program is free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License as published by
11 * the Free Software Foundation; either version 2 of the License, or
12 * (at your option) any later version.
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU General Public License for more details.
19 * You should have received a copy of the GNU General Public License along
20 * with this program; if not, write to the Free Software Foundation, Inc.,
21 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
22 * http://www.gnu.org/copyleft/gpl.html
27 use HtmlFormatter\HtmlFormatter
;
28 use MediaWiki\MediaWikiServices
;
31 * Class to output help for an API module
33 * @since 1.25 completely rewritten
36 class ApiHelp
extends ApiBase
{
37 public function execute() {
38 $params = $this->extractRequestParams();
41 foreach ( $params['modules'] as $path ) {
42 $modules[] = $this->getModuleFromPath( $path );
46 $context = new DerivativeContext( $this->getMain()->getContext() );
47 $context->setSkin( SkinFactory
::getDefaultInstance()->makeSkin( 'apioutput' ) );
48 $context->setLanguage( $this->getMain()->getLanguage() );
49 $context->setTitle( SpecialPage
::getTitleFor( 'ApiHelp' ) );
50 $out = new OutputPage( $context );
51 $out->setCopyrightUrl( 'https://www.mediawiki.org/wiki/Special:MyLanguage/Copyright' );
52 $context->setOutput( $out );
54 self
::getHelp( $context, $modules, $params );
56 // Grab the output from the skin
58 $context->getOutput()->output();
59 $html = ob_get_clean();
61 $result = $this->getResult();
62 if ( $params['wrap'] ) {
64 'mime' => 'text/html',
65 'filename' => 'api-help.html',
68 ApiResult
::setSubelementsList( $data, 'help' );
69 $result->addValue( null, $this->getModuleName(), $data );
72 $result->addValue( null, 'text', $html, ApiResult
::NO_SIZE_CHECK
);
73 $result->addValue( null, 'mime', 'text/html', ApiResult
::NO_SIZE_CHECK
);
74 $result->addValue( null, 'filename', 'api-help.html', ApiResult
::NO_SIZE_CHECK
);
79 * Generate help for the specified modules
81 * Help is placed into the OutputPage object returned by
82 * $context->getOutput().
84 * Recognized options include:
85 * - headerlevel: (int) Header tag level
86 * - nolead: (bool) Skip the inclusion of api-help-lead
87 * - noheader: (bool) Skip the inclusion of the top-level section headers
88 * - submodules: (bool) Include help for submodules of the current module
89 * - recursivesubmodules: (bool) Include help for submodules recursively
90 * - helptitle: (string) Title to link for additional modules' help. Should contain $1.
91 * - toc: (bool) Include a table of contents
93 * @param IContextSource $context
94 * @param ApiBase[]|ApiBase $modules
95 * @param array $options Formatting options (described above)
97 public static function getHelp( IContextSource
$context, $modules, array $options ) {
100 if ( !is_array( $modules ) ) {
101 $modules = [ $modules ];
104 $out = $context->getOutput();
105 $out->addModuleStyles( [
109 if ( !empty( $options['toc'] ) ) {
110 $out->addModules( 'mediawiki.toc' );
112 $out->setPageTitle( $context->msg( 'api-help-title' ) );
114 $cache = MediaWikiServices
::getInstance()->getMainWANObjectCache();
116 if ( count( $modules ) == 1 && $modules[0] instanceof ApiMain
&&
117 $options['recursivesubmodules'] && $context->getLanguage() === $wgContLang
119 $cacheHelpTimeout = $context->getConfig()->get( 'APICacheHelpTimeout' );
120 if ( $cacheHelpTimeout > 0 ) {
121 // Get help text from cache if present
122 $cacheKey = $cache->makeKey( 'apihelp', $modules[0]->getModulePath(),
123 (int)!empty( $options['toc'] ),
124 str_replace( ' ', '_', SpecialVersion
::getVersion( 'nodb' ) ) );
125 $cached = $cache->get( $cacheKey );
127 $out->addHTML( $cached );
132 if ( $out->getHTML() !== '' ) {
133 // Don't save to cache, there's someone else's content in the page
138 $options['recursivesubmodules'] = !empty( $options['recursivesubmodules'] );
139 $options['submodules'] = $options['recursivesubmodules'] ||
!empty( $options['submodules'] );
142 if ( empty( $options['nolead'] ) ) {
143 $msg = $context->msg( 'api-help-lead' );
144 if ( !$msg->isDisabled() ) {
145 $out->addHTML( $msg->parseAsBlock() );
150 $html = self
::getHelpInternal( $context, $modules, $options, $haveModules );
151 if ( !empty( $options['toc'] ) && $haveModules ) {
152 $out->addHTML( Linker
::generateTOC( $haveModules, $context->getLanguage() ) );
154 $out->addHTML( $html );
156 $helptitle = isset( $options['helptitle'] ) ?
$options['helptitle'] : null;
157 $html = self
::fixHelpLinks( $out->getHTML(), $helptitle, $haveModules );
159 $out->addHTML( $html );
161 if ( $cacheKey !== null ) {
162 $cache->set( $cacheKey, $out->getHTML(), $cacheHelpTimeout );
167 * Replace Special:ApiHelp links with links to api.php
169 * @param string $html
170 * @param string|null $helptitle Title to link to rather than api.php, must contain '$1'
171 * @param array $localModules Keys are modules to link within the current page, values are ignored
174 public static function fixHelpLinks( $html, $helptitle = null, $localModules = [] ) {
175 $formatter = new HtmlFormatter( $html );
176 $doc = $formatter->getDoc();
177 $xpath = new DOMXPath( $doc );
178 $nodes = $xpath->query( '//a[@href][not(contains(@class,\'apihelp-linktrail\'))]' );
179 foreach ( $nodes as $node ) {
180 $href = $node->getAttribute( 'href' );
183 $href = rawurldecode( $href );
184 } while ( $old !== $href );
185 if ( preg_match( '!Special:ApiHelp/([^&/|#]+)((?:#.*)?)!', $href, $m ) ) {
186 if ( isset( $localModules[$m[1]] ) ) {
187 $href = $m[2] === '' ?
'#' . $m[1] : $m[2];
188 } elseif ( $helptitle !== null ) {
189 $href = Title
::newFromText( str_replace( '$1', $m[1], $helptitle ) . $m[2] )
192 $href = wfAppendQuery( wfScript( 'api' ), [
197 $node->setAttribute( 'href', $href );
198 $node->removeAttribute( 'title' );
202 return $formatter->getText();
206 * Wrap a message in HTML with a class.
208 * @param Message $msg
209 * @param string $class
213 private static function wrap( Message
$msg, $class, $tag = 'span' ) {
214 return Html
::rawElement( $tag, [ 'class' => $class ],
220 * Recursively-called function to actually construct the help
222 * @param IContextSource $context
223 * @param ApiBase[] $modules
224 * @param array $options
225 * @param array &$haveModules
228 private static function getHelpInternal( IContextSource
$context, array $modules,
229 array $options, &$haveModules
233 $level = empty( $options['headerlevel'] ) ?
2 : $options['headerlevel'];
234 if ( empty( $options['tocnumber'] ) ) {
235 $tocnumber = [ 2 => 0 ];
237 $tocnumber = &$options['tocnumber'];
240 foreach ( $modules as $module ) {
241 $tocnumber[$level]++
;
242 $path = $module->getModulePath();
243 $module->setContext( $context );
254 if ( empty( $options['noheader'] ) ||
!empty( $options['toc'] ) ) {
257 while ( isset( $haveModules[$anchor] ) ) {
258 $anchor = $path . '|' . ++
$i;
261 if ( $module->isMain() ) {
262 $headerContent = $context->msg( 'api-help-main-header' )->parse();
264 'class' => 'apihelp-header',
267 $name = $module->getModuleName();
268 $headerContent = $module->getParent()->getModuleManager()->getModuleGroup( $name ) .
270 if ( $module->getModulePrefix() !== '' ) {
271 $headerContent .= ' ' .
272 $context->msg( 'parentheses', $module->getModulePrefix() )->parse();
274 // Module names are always in English and not localized,
275 // so English language and direction must be set explicitly,
276 // otherwise parentheses will get broken in RTL wikis
278 'class' => 'apihelp-header apihelp-module-name',
284 $headerAttr['id'] = $anchor;
286 $haveModules[$anchor] = [
287 'toclevel' => count( $tocnumber ),
290 'line' => $headerContent,
291 'number' => implode( '.', $tocnumber ),
294 if ( empty( $options['noheader'] ) ) {
295 $help['header'] .= Html
::element(
296 'h' . min( 6, $level ),
302 $haveModules[$path] = true;
307 for ( $m = $module; $m !== null; $m = $m->getParent() ) {
308 $name = $m->getModuleName();
309 if ( $name === 'main_int' ) {
313 if ( count( $modules ) === 1 && $m === $modules[0] &&
314 !( !empty( $options['submodules'] ) && $m->getModuleManager() )
316 $link = Html
::element( 'b', [ 'dir' => 'ltr', 'lang' => 'en' ], $name );
318 $link = SpecialPage
::getTitleFor( 'ApiHelp', $m->getModulePath() )->getLocalURL();
319 $link = Html
::element( 'a',
320 [ 'href' => $link, 'class' => 'apihelp-linktrail', 'dir' => 'ltr', 'lang' => 'en' ],
325 array_unshift( $links, $link );
328 $help['header'] .= self
::wrap(
329 $context->msg( 'parentheses' )
330 ->rawParams( $context->getLanguage()->pipeList( $links ) ),
331 'apihelp-linktrail', 'div'
335 $flags = $module->getHelpFlags();
336 $help['flags'] .= Html
::openElement( 'div',
337 [ 'class' => 'apihelp-block apihelp-flags' ] );
338 $msg = $context->msg( 'api-help-flags' );
339 if ( !$msg->isDisabled() ) {
340 $help['flags'] .= self
::wrap(
341 $msg->numParams( count( $flags ) ), 'apihelp-block-head', 'div'
344 $help['flags'] .= Html
::openElement( 'ul' );
345 foreach ( $flags as $flag ) {
346 $help['flags'] .= Html
::rawElement( 'li', null,
347 self
::wrap( $context->msg( "api-help-flag-$flag" ), "apihelp-flag-$flag" )
350 $sourceInfo = $module->getModuleSourceInfo();
352 if ( isset( $sourceInfo['namemsg'] ) ) {
353 $extname = $context->msg( $sourceInfo['namemsg'] )->text();
355 // Probably English, so wrap it.
356 $extname = Html
::element( 'span', [ 'dir' => 'ltr', 'lang' => 'en' ], $sourceInfo['name'] );
358 $help['flags'] .= Html
::rawElement( 'li', null,
360 $context->msg( 'api-help-source', $extname, $sourceInfo['name'] ),
365 $link = SpecialPage
::getTitleFor( 'Version', 'License/' . $sourceInfo['name'] );
366 if ( isset( $sourceInfo['license-name'] ) ) {
367 $msg = $context->msg( 'api-help-license', $link,
368 Html
::element( 'span', [ 'dir' => 'ltr', 'lang' => 'en' ], $sourceInfo['license-name'] )
370 } elseif ( SpecialVersion
::getExtLicenseFileName( dirname( $sourceInfo['path'] ) ) ) {
371 $msg = $context->msg( 'api-help-license-noname', $link );
373 $msg = $context->msg( 'api-help-license-unknown' );
375 $help['flags'] .= Html
::rawElement( 'li', null,
376 self
::wrap( $msg, 'apihelp-license' )
379 $help['flags'] .= Html
::rawElement( 'li', null,
380 self
::wrap( $context->msg( 'api-help-source-unknown' ), 'apihelp-source' )
382 $help['flags'] .= Html
::rawElement( 'li', null,
383 self
::wrap( $context->msg( 'api-help-license-unknown' ), 'apihelp-license' )
386 $help['flags'] .= Html
::closeElement( 'ul' );
387 $help['flags'] .= Html
::closeElement( 'div' );
389 foreach ( $module->getFinalDescription() as $msg ) {
390 $msg->setContext( $context );
391 $help['description'] .= $msg->parseAsBlock();
394 $urls = $module->getHelpUrls();
396 $help['help-urls'] .= Html
::openElement( 'div',
397 [ 'class' => 'apihelp-block apihelp-help-urls' ]
399 $msg = $context->msg( 'api-help-help-urls' );
400 if ( !$msg->isDisabled() ) {
401 $help['help-urls'] .= self
::wrap(
402 $msg->numParams( count( $urls ) ), 'apihelp-block-head', 'div'
405 if ( !is_array( $urls ) ) {
408 $help['help-urls'] .= Html
::openElement( 'ul' );
409 foreach ( $urls as $url ) {
410 $help['help-urls'] .= Html
::rawElement( 'li', null,
411 Html
::element( 'a', [ 'href' => $url, 'dir' => 'ltr' ], $url )
414 $help['help-urls'] .= Html
::closeElement( 'ul' );
415 $help['help-urls'] .= Html
::closeElement( 'div' );
418 $params = $module->getFinalParams( ApiBase
::GET_VALUES_FOR_HELP
);
419 $dynamicParams = $module->dynamicParameterDocumentation();
421 if ( $params ||
$dynamicParams !== null ) {
422 $help['parameters'] .= Html
::openElement( 'div',
423 [ 'class' => 'apihelp-block apihelp-parameters' ]
425 $msg = $context->msg( 'api-help-parameters' );
426 if ( !$msg->isDisabled() ) {
427 $help['parameters'] .= self
::wrap(
428 $msg->numParams( count( $params ) ), 'apihelp-block-head', 'div'
431 $help['parameters'] .= Html
::openElement( 'dl' );
433 $descriptions = $module->getFinalParamDescription();
435 foreach ( $params as $name => $settings ) {
436 if ( !is_array( $settings ) ) {
437 $settings = [ ApiBase
::PARAM_DFLT
=> $settings ];
440 $help['parameters'] .= Html
::rawElement( 'dt', null,
441 Html
::element( 'span', [ 'dir' => 'ltr', 'lang' => 'en' ], $module->encodeParamName( $name ) )
446 if ( isset( $descriptions[$name] ) ) {
447 foreach ( $descriptions[$name] as $msg ) {
448 $msg->setContext( $context );
449 $description[] = $msg->parseAsBlock();
457 if ( !empty( $settings[ApiBase
::PARAM_REQUIRED
] ) ) {
458 $info[] = $context->msg( 'api-help-param-required' )->parse();
462 if ( !empty( $settings[ApiBase
::PARAM_HELP_MSG_INFO
] ) ) {
463 foreach ( $settings[ApiBase
::PARAM_HELP_MSG_INFO
] as $i ) {
464 $tag = array_shift( $i );
465 $info[] = $context->msg( "apihelp-{$path}-paraminfo-{$tag}" )
466 ->numParams( count( $i ) )
467 ->params( $context->getLanguage()->commaList( $i ) )
468 ->params( $module->getModulePrefix() )
473 // Type documentation
474 if ( !isset( $settings[ApiBase
::PARAM_TYPE
] ) ) {
475 $dflt = isset( $settings[ApiBase
::PARAM_DFLT
] )
476 ?
$settings[ApiBase
::PARAM_DFLT
]
478 if ( is_bool( $dflt ) ) {
479 $settings[ApiBase
::PARAM_TYPE
] = 'boolean';
480 } elseif ( is_string( $dflt ) ||
is_null( $dflt ) ) {
481 $settings[ApiBase
::PARAM_TYPE
] = 'string';
482 } elseif ( is_int( $dflt ) ) {
483 $settings[ApiBase
::PARAM_TYPE
] = 'integer';
486 if ( isset( $settings[ApiBase
::PARAM_TYPE
] ) ) {
487 $type = $settings[ApiBase
::PARAM_TYPE
];
488 $multi = !empty( $settings[ApiBase
::PARAM_ISMULTI
] );
489 $hintPipeSeparated = true;
490 $count = !empty( $settings[ApiBase
::PARAM_ISMULTI_LIMIT2
] )
491 ?
$settings[ApiBase
::PARAM_ISMULTI_LIMIT2
] +
1
492 : ApiBase
::LIMIT_SML2 +
1;
494 if ( is_array( $type ) ) {
495 $count = count( $type );
496 $deprecatedValues = isset( $settings[ApiBase
::PARAM_DEPRECATED_VALUES
] )
497 ?
$settings[ApiBase
::PARAM_DEPRECATED_VALUES
]
499 $links = isset( $settings[ApiBase
::PARAM_VALUE_LINKS
] )
500 ?
$settings[ApiBase
::PARAM_VALUE_LINKS
]
502 $values = array_map( function ( $v ) use ( $links, $deprecatedValues ) {
505 // We can't know whether this contains LTR or RTL text.
506 $attr['dir'] = 'auto';
508 if ( isset( $deprecatedValues[$v] ) ) {
509 $attr['class'] = 'apihelp-deprecated-value';
511 $ret = $attr ? Html
::element( 'span', $attr, $v ) : $v;
512 if ( isset( $links[$v] ) ) {
513 $ret = "[[{$links[$v]}|$ret]]";
517 $i = array_search( '', $type, true );
518 if ( $i === false ) {
519 $values = $context->getLanguage()->commaList( $values );
521 unset( $values[$i] );
522 $values = $context->msg( 'api-help-param-list-can-be-empty' )
523 ->numParams( count( $values ) )
524 ->params( $context->getLanguage()->commaList( $values ) )
527 $info[] = $context->msg( 'api-help-param-list' )
528 ->params( $multi ?
2 : 1 )
531 $hintPipeSeparated = false;
537 if ( isset( $settings[ApiBase
::PARAM_SUBMODULE_MAP
] ) ) {
538 $map = $settings[ApiBase
::PARAM_SUBMODULE_MAP
];
541 $prefix = $module->isMain() ?
'' : ( $module->getModulePath() . '+' );
543 foreach ( $module->getModuleManager()->getNames( $name ) as $submoduleName ) {
544 $map[$submoduleName] = $prefix . $submoduleName;
546 $defaultAttrs = [ 'dir' => 'ltr', 'lang' => 'en' ];
551 $deprecatedSubmodules = [];
552 foreach ( $map as $v => $m ) {
553 $attrs = $defaultAttrs;
556 $submod = $module->getModuleFromPath( $m );
558 if ( $submod->isDeprecated() ) {
559 $arr = &$deprecatedSubmodules;
560 $attrs['class'] = 'apihelp-deprecated-value';
563 } catch ( ApiUsageException
$ex ) {
567 $v = Html
::element( 'span', $attrs, $v );
569 $arr[] = "[[Special:ApiHelp/{$m}|{$v}]]";
571 $submodules = array_merge( $submodules, $deprecatedSubmodules );
572 $count = count( $submodules );
573 $info[] = $context->msg( 'api-help-param-list' )
574 ->params( $multi ?
2 : 1 )
575 ->params( $context->getLanguage()->commaList( $submodules ) )
577 $hintPipeSeparated = false;
578 // No type message necessary, we have a list of values.
583 $namespaces = MWNamespace
::getValidNamespaces();
584 if ( isset( $settings[ApiBase
::PARAM_EXTRA_NAMESPACES
] ) &&
585 is_array( $settings[ApiBase
::PARAM_EXTRA_NAMESPACES
] )
587 $namespaces = array_merge( $namespaces, $settings[ApiBase
::PARAM_EXTRA_NAMESPACES
] );
590 $count = count( $namespaces );
591 $info[] = $context->msg( 'api-help-param-list' )
592 ->params( $multi ?
2 : 1 )
593 ->params( $context->getLanguage()->commaList( $namespaces ) )
595 $hintPipeSeparated = false;
596 // No type message necessary, we have a list of values.
601 $tags = ChangeTags
::listExplicitlyDefinedTags();
602 $count = count( $tags );
603 $info[] = $context->msg( 'api-help-param-list' )
604 ->params( $multi ?
2 : 1 )
605 ->params( $context->getLanguage()->commaList( $tags ) )
607 $hintPipeSeparated = false;
612 if ( isset( $settings[ApiBase
::PARAM_MAX2
] ) ) {
613 $info[] = $context->msg( 'api-help-param-limit2' )
614 ->numParams( $settings[ApiBase
::PARAM_MAX
] )
615 ->numParams( $settings[ApiBase
::PARAM_MAX2
] )
618 $info[] = $context->msg( 'api-help-param-limit' )
619 ->numParams( $settings[ApiBase
::PARAM_MAX
] )
625 // Possible messages:
626 // api-help-param-integer-min,
627 // api-help-param-integer-max,
628 // api-help-param-integer-minmax
631 if ( isset( $settings[ApiBase
::PARAM_MIN
] ) ) {
633 $min = $settings[ApiBase
::PARAM_MIN
];
635 if ( isset( $settings[ApiBase
::PARAM_MAX
] ) ) {
637 $max = $settings[ApiBase
::PARAM_MAX
];
639 if ( $suffix !== '' ) {
641 $context->msg( "api-help-param-integer-$suffix" )
642 ->params( $multi ?
2 : 1 )
643 ->numParams( $min, $max )
649 $info[] = $context->msg( 'api-help-param-upload' )
651 // No type message necessary, api-help-param-upload should handle it.
657 // Displaying a type message here would be useless.
663 // Add type. Messages for grep: api-help-param-type-limit
664 // api-help-param-type-integer api-help-param-type-boolean
665 // api-help-param-type-timestamp api-help-param-type-user
666 // api-help-param-type-password
667 if ( is_string( $type ) ) {
668 $msg = $context->msg( "api-help-param-type-$type" );
669 if ( !$msg->isDisabled() ) {
670 $info[] = $msg->params( $multi ?
2 : 1 )->parse();
676 $lowcount = !empty( $settings[ApiBase
::PARAM_ISMULTI_LIMIT1
] )
677 ?
$settings[ApiBase
::PARAM_ISMULTI_LIMIT1
]
678 : ApiBase
::LIMIT_SML1
;
679 $highcount = !empty( $settings[ApiBase
::PARAM_ISMULTI_LIMIT2
] )
680 ?
$settings[ApiBase
::PARAM_ISMULTI_LIMIT2
]
681 : ApiBase
::LIMIT_SML2
;
683 if ( $hintPipeSeparated ) {
684 $extra[] = $context->msg( 'api-help-param-multi-separate' )->parse();
686 if ( $count > $lowcount ) {
687 if ( $lowcount === $highcount ) {
688 $msg = $context->msg( 'api-help-param-multi-max-simple' )
689 ->numParams( $lowcount );
691 $msg = $context->msg( 'api-help-param-multi-max' )
692 ->numParams( $lowcount, $highcount );
694 $extra[] = $msg->parse();
697 $info[] = implode( ' ', $extra );
700 $allowAll = isset( $settings[ApiBase
::PARAM_ALL
] )
701 ?
$settings[ApiBase
::PARAM_ALL
]
703 if ( $allowAll ||
$settings[ApiBase
::PARAM_TYPE
] === 'namespace' ) {
704 if ( $settings[ApiBase
::PARAM_TYPE
] === 'namespace' ) {
705 $allSpecifier = ApiBase
::ALL_DEFAULT_STRING
;
707 $allSpecifier = ( is_string( $allowAll ) ?
$allowAll : ApiBase
::ALL_DEFAULT_STRING
);
709 $info[] = $context->msg( 'api-help-param-multi-all' )
710 ->params( $allSpecifier )
716 if ( isset( $settings[self
::PARAM_MAX_BYTES
] ) ) {
717 $info[] = $context->msg( 'api-help-param-maxbytes' )
718 ->numParams( $settings[self
::PARAM_MAX_BYTES
] );
720 if ( isset( $settings[self
::PARAM_MAX_CHARS
] ) ) {
721 $info[] = $context->msg( 'api-help-param-maxchars' )
722 ->numParams( $settings[self
::PARAM_MAX_CHARS
] );
726 $default = isset( $settings[ApiBase
::PARAM_DFLT
] )
727 ?
$settings[ApiBase
::PARAM_DFLT
]
729 if ( $default === '' ) {
730 $info[] = $context->msg( 'api-help-param-default-empty' )
732 } elseif ( $default !== null && $default !== false ) {
733 // We can't know whether this contains LTR or RTL text.
734 $info[] = $context->msg( 'api-help-param-default' )
735 ->params( Html
::element( 'span', [ 'dir' => 'auto' ], $default ) )
739 if ( !array_filter( $description ) ) {
740 $description = [ self
::wrap(
741 $context->msg( 'api-help-param-no-description' ),
746 // Add "deprecated" flag
747 if ( !empty( $settings[ApiBase
::PARAM_DEPRECATED
] ) ) {
748 $help['parameters'] .= Html
::openElement( 'dd',
749 [ 'class' => 'info' ] );
750 $help['parameters'] .= self
::wrap(
751 $context->msg( 'api-help-param-deprecated' ),
752 'apihelp-deprecated', 'strong'
754 $help['parameters'] .= Html
::closeElement( 'dd' );
757 if ( $description ) {
758 $description = implode( '', $description );
759 $description = preg_replace( '!\s*</([oud]l)>\s*<\1>\s*!', "\n", $description );
760 $help['parameters'] .= Html
::rawElement( 'dd',
761 [ 'class' => 'description' ], $description );
764 foreach ( $info as $i ) {
765 $help['parameters'] .= Html
::rawElement( 'dd', [ 'class' => 'info' ], $i );
769 if ( $dynamicParams !== null ) {
770 $dynamicParams = ApiBase
::makeMessage( $dynamicParams, $context, [
771 $module->getModulePrefix(),
772 $module->getModuleName(),
773 $module->getModulePath()
775 $help['parameters'] .= Html
::element( 'dt', null, '*' );
776 $help['parameters'] .= Html
::rawElement( 'dd',
777 [ 'class' => 'description' ], $dynamicParams->parse() );
780 $help['parameters'] .= Html
::closeElement( 'dl' );
781 $help['parameters'] .= Html
::closeElement( 'div' );
784 $examples = $module->getExamplesMessages();
786 $help['examples'] .= Html
::openElement( 'div',
787 [ 'class' => 'apihelp-block apihelp-examples' ] );
788 $msg = $context->msg( 'api-help-examples' );
789 if ( !$msg->isDisabled() ) {
790 $help['examples'] .= self
::wrap(
791 $msg->numParams( count( $examples ) ), 'apihelp-block-head', 'div'
795 $help['examples'] .= Html
::openElement( 'dl' );
796 foreach ( $examples as $qs => $msg ) {
797 $msg = ApiBase
::makeMessage( $msg, $context, [
798 $module->getModulePrefix(),
799 $module->getModuleName(),
800 $module->getModulePath()
803 $link = wfAppendQuery( wfScript( 'api' ), $qs );
804 $sandbox = SpecialPage
::getTitleFor( 'ApiSandbox' )->getLocalURL() . '#' . $qs;
805 $help['examples'] .= Html
::rawElement( 'dt', null, $msg->parse() );
806 $help['examples'] .= Html
::rawElement( 'dd', null,
807 Html
::element( 'a', [ 'href' => $link, 'dir' => 'ltr' ], "api.php?$qs" ) . ' ' .
808 Html
::rawElement( 'a', [ 'href' => $sandbox ],
809 $context->msg( 'api-help-open-in-apisandbox' )->parse() )
812 $help['examples'] .= Html
::closeElement( 'dl' );
813 $help['examples'] .= Html
::closeElement( 'div' );
816 $subtocnumber = $tocnumber;
817 $subtocnumber[$level +
1] = 0;
819 'submodules' => $options['recursivesubmodules'],
820 'headerlevel' => $level +
1,
821 'tocnumber' => &$subtocnumber,
825 if ( $options['submodules'] && $module->getModuleManager() ) {
826 $manager = $module->getModuleManager();
828 foreach ( $groups as $group ) {
829 $names = $manager->getNames( $group );
831 foreach ( $names as $name ) {
832 $submodules[] = $manager->getModule( $name );
835 $help['submodules'] .= self
::getHelpInternal(
843 $module->modifyHelp( $help, $suboptions, $haveModules );
845 Hooks
::run( 'APIHelpModifyOutput', [ $module, &$help, $suboptions, &$haveModules ] );
847 $out .= implode( "\n", $help );
853 public function shouldCheckMaxlag() {
857 public function isReadMode() {
861 public function getCustomPrinter() {
862 $params = $this->extractRequestParams();
863 if ( $params['wrap'] ) {
867 $main = $this->getMain();
868 $errorPrinter = $main->createPrinterByName( $main->getParameter( 'format' ) );
869 return new ApiFormatRaw( $main, $errorPrinter );
872 public function getAllowedParams() {
875 ApiBase
::PARAM_DFLT
=> 'main',
876 ApiBase
::PARAM_ISMULTI
=> true,
878 'submodules' => false,
879 'recursivesubmodules' => false,
885 protected function getExamplesMessages() {
888 => 'apihelp-help-example-main',
889 'action=help&modules=query&submodules=1'
890 => 'apihelp-help-example-submodules',
891 'action=help&recursivesubmodules=1'
892 => 'apihelp-help-example-recursive',
893 'action=help&modules=help'
894 => 'apihelp-help-example-help',
895 'action=help&modules=query+info|query+categorymembers'
896 => 'apihelp-help-example-query',
900 public function getHelpUrls() {
902 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Main_page',
903 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:FAQ',
904 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Quick_start_guide',